/*
 * Copyright (C) 2015 Miquel Sas
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package traderlib.core.data.entity;

import java.util.List;
import traderlib.core.data.types.Value;

/**
 * An Entity is a documented value structure, that is, a list of values with their correspondent field definitions.
 *
 * @author Miquel Sas
 */
public interface Entity {

	/**
	 * Returns the name of this entity, normally the name of this entity peer.
	 *
	 * @return The name.
	 */
	public String getName();

	/**
	 * Returns the alias of this entity.
	 *
	 * @return The alias.
	 */
	public String getAlias();

	/**
	 * Returns the description of this entity.
	 *
	 * @return The description.
	 */
	public String getDescription();

	/**
	 * Returns the list with all relations.
	 *
	 * @return The list of relations.
	 */
	public List<Relation> getRelations();

	/**
	 * Clears this entity fields to their default values.
	 */
	public void clear();

	/**
	 * Returns the number of fields.
	 *
	 * @return The number of fields.
	 */
	public int getFieldCount();

	/**
	 * Returns the field index given the field alias.
	 *
	 * @return The field index.
	 * @param alias The field alias.
	 */
	public int getFieldIndex(String alias);

	/**
	 * Returns a field given its index.
	 *
	 * @return The field.
	 * @param index The field index.
	 */
	public Field getField(int index);

	/**
	 * Returns a field given its alias, or null if not found.
	 *
	 * @return The field.
	 * @param alias The field alias.
	 */
	public Field getField(String alias);

	/**
	 * Returns a value given its field index.
	 *
	 * @param index The value/field index.
	 * @return The value.
	 */
	public Value getValue(int index);

	/**
	 * Returns a value given its field alias.
	 *
	 * @param alias The value/field alias.
	 * @return The value.
	 */
	public Value getValue(String alias);

	/**
	 * Returns an entity that is a copy of this entity. The new entity should be independent, that is, assigning values
	 * to the fields should not modify the original one.
	 *
	 * @return A copy of this entity.
	 */
	public Entity copy();

	/**
	 * Check if this entity exists.
	 *
	 * @return A boolean
	 * @throws EntityException
	 */
	public boolean exists() throws EntityException;

	/**
	 * Inserts the entity in its source of persistence.
	 *
	 * @return The number of updates (1 or 0)
	 * @throws EntityException
	 */
	public int insert() throws EntityException;

	/**
	 * Deletes this entity in a persistent manner.
	 *
	 * @return The number of updates (1 or 0)
	 * @throws EntityException
	 */
	public int delete() throws EntityException;

	/**
	 * Save the entity, inserting if it does not exist or updating if it does exist.
	 *
	 * @return The number of entities updated or inserted.
	 * @throws EntityException
	 */
	public int save() throws EntityException;

	/**
	 * Permanently updates this entity in the source of persistence.
	 *
	 * @return The number of updates (1 or 0)
	 * @throws EntityException
	 */
	public int update() throws EntityException;

	/**
	 * Refreshes this entity field values from the source of persistence based on primary key of entity.
	 *
	 * @return A <code>boolean</code> indicating that the operation has been successfull.
	 * @throws EntityException
	 */
	public boolean refresh() throws EntityException;
}
